Gold Medal Software 3

home *** CD-ROM | disk | FTP | other *** search

/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / os2 / te2_130t.arj / TE2INST.006 / Script.Doc next >

Wrap

Text File | 1994-04-08 | 75KB | 1,556 lines

TE/2 Script Language Function Listing 11 April, 1994 Oberon Software 1405 East Main Street Mankato, MN 56001-5070 ------------------------------------------------------------- Copyright 1990-94, Oberon Software, Mankato, MN - All Rights Reserved ------------------------------------------------------------- ---------------------------------------------------- Notice: Information in this document is subject to change without notice and does not constitute a commitment on the part of Oberon Software. ---------------------------------------------------- ABS(integer) Returns: INTEGER, the absolute value of its argument ASCIIVAL(string) Returns: INTEGER, the ASCII value of the first character of its argument ATOI(string) Returns: INTEGER, the numeric value of the argument Notes: this function understands hex and octal notation, thus ATOI("27") and ATOI("0x1b") and ATOI("033") all return the same value, 27. BEEP(integer, integer) Returns: INTEGER, always TRUE Notes: this function will sound the console beeper, the first parameter specifies the frequency (pitch) of the sound, the second the duration. CANCELWATCH(integer) Returns: INTEGER, TRUE or FALSE Notes: The argument must be a 'watch handle' created via a previous call to WATCHFOR. This function releases the watch. It returns FALSE if the watch did not exist, TRUE otherwise. See also WATCHFOR. CHAT(void) Returns: INTEGER, always TRUE Notes: Activates chat mode, same as Alt-G from terminal mode CHDIR(string) Returns: INTEGER, TRUE or FALSE Notes: the argument specifies a subdirectory, this function will attempt to change the current working directory on the current or specified disk, it will NOT change the currently logged disk however. CHDIR returns TRUE if it was successful. (See CHDISK) Examples: CHDIR("D:\") CHDIR("\comm\log") CHDISK(string) Returns: INTEGER, TRUE or FALSE Notes: the first character of the argument should specify a disk letter. This function will attempt to make that the current drive. It returns TRUE if it was successful. (See CHDIR) CLOSEDIALOG(integer) Returns: INTEGER, always TRUE Notes: The argument MUST be a handle to a dialog that has been created by an earlier call to OPENDIALOG. Restores the area of the screen which was saved during the OPENDIALOG call and frees up all memory associated with this dialog. CLS(void) Returns: INTEGER, always TRUE Notes: Clears the terminal screen to the current attribute. CRC16(string, integer) Returns: INTEGER Notes: The numeric parameter specifies the how many bytes of the string to consider, if set to -1 then the entire string is used. The function returns the 16-bit CRC for the string. CRC32(string, integer) Returns: INTEGER Notes: The numeric parameter specifies the how many bytes of the string to consider, if set to -1 then the entire string is used. The function returns the 32-bit CRC for the string. DIAL(string OR integer) Returns: INTEGER, TRUE or FALSE Notes: If the argument is an integer or if it is a string with the format "#nnn" where the n's are digits, DIAL will attempt to dial the indicated entry in the current dialing directory. If it is a string and not "#nnn" format, then if the first character is a digit it will manually dial the string, else if the string is not empty it will search for a TAG in the current dialing directory that matches and dial that entry. If the string is empty, the user is prompted for a number (this is equivalent to typing Alt-M from terminal mode). DIAL returns TRUE if a connection was made. DIRECTORY(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-D from terminal mode. DIRECTORY returns TRUE if a connection was made. DIRNAME(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory, "#nnn" where "nnn" is an entry's position in the directory, or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Name" field in the specified entry or "" if it could not be located. DIRPHONE(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory, "#nnn" where "nnn" is an entry's position in the directory, or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Number" field in the specified entry or "" if it could not be located. DIRSCRIPT(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory, "#nnn" where "nnn" is an entry's position in the directory, or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Script" field in the specified entry or "" if it could not be located. DIRTAG(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory, "#nnn" where "nnn" is an entry's position in the directory, or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Tag" field in the specified entry or "" if it could not be located. DOWNLOAD(special, string) Returns: INTEGER, TRUE or FALSE Notes: The "special" parameter must be one of the following pre-defined constants: XMODEM, XMODEM1K, YMODEM, YMODEMG, ZMODEM, or QUERY. If this parameter is QUERY, the user is prompted for the protocol. The second parameter is the file name, if it is the empty string, XMODEM and XMODEM1K will prompt the user for the filename, this parameter is ignored by YMODEM, YMODEMG, and ZMODEM. The function returns TRUE if the file transfer ended with no fatal errors. (See UPLOAD) DRAWBOX(integer, integer, integer, integer, integer, integer, integer) Returns: INTEGER, TRUE (success) or FALSE (error) Notes: The parameters are, in order: Row - 1 to ScreenLines Col - 1 to ScreenCols NumRows - 1 to ScreenLines NumCols - 1 to ScreenCols Attribute - 0 to 255, any valid color attribute Style - 0:No frame, 1:single lines, 2:double lines Fill - TRUE or FALSE DUMPINIT(void) Returns: INTEGER, always TRUE Notes: Prints the current value of all the system-global values settable via TE2.INI to the terminal screen. EMULATE(special) Returns: INTEGER, the new emulation. Notes: The "special" parameter must be one of the following pre-defined constants: TTY, ANSI_BBS, ANSI_TE2, VT100, or QUERY. If it is QUERY, the user is prompted for the emulation. ERASE(string) Returns: INTEGER, 0 on success, -1 on error Notes: This function will delete the indicated file from the disk. Clearly, you should use this function with care. ERRORMSG(string, string) Returns: INTEGER, always TRUE Notes: Displays the error message dialog (TE/2 uses this dialog for most all, non-script related errors). String1 is left justified on the first line of the dialog, string2 centered on the second and "Strike any key to continue" is placed at the bottom of the dialog. ErrorAttr from the initialization file is used for the dialog color. The portion of the screen overlaid by the dialog is saved and restored when the dialog is exited. EXECPGM(string, string, string, integer, integer) Returns: INTEGER Notes: The arguments are, in order, session_title, program_name, program_args, exec_type, and exec_flags. These parameters map directly to the information contained in the external program file that TE/2 uses to build the "User Programs" menu (Alt-J), you should refer to the TE/2 Manual for more information on these settings. All of the functionality for user input and global value passing that is referred to there is present here. The exec_flags parameter is NOT optional for this call like it is in the external programs file however. The return value of EXECPGM() depends on the mode in which the child process was executed. A return value of -1 will usually indicate an invalid parameter list. If the child was executed in the background or in a new session, the return value is zero for success or the error code which was returned by OS/2. If the child was executed as a foreground process, the return value is the exit code of the child program (i.e., the value which it passed to DosExit()). EXIT(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" parameter must be one of the following pre-defined constants: TRUE, FALSE, IFCARRIER. If it is FALSE, the user will be asked for confirmation before exiting, if TRUE TE/2 will unconditionally exit, if QUERY the user will be queried only if the carrier is high (TE/2 is online). The function returns TRUE if TE/2 is exiting (although you won't be able to test this, if the function returns to the script at all it should do so with FALSE). FNKEY(integer) Returns: INTEGER, TRUE or FALSE Notes: If the argument is zero or greater than 48, the function key menu is activated, this is equivalent to typing Alt-K from terminal mode. If it is a number from 1 to 48, the corresponding function key macro is transmitted. 1 - 12 -> unshifed function keys 1-12 13 - 24 -> shifted function keys 1-12 25 - 36 -> control-function keys 1-12 37 - 48 -> alt-function keys 1-12 The function returns TRUE if a macro was transmitted. FCLOSE(integer) Returns: INTEGER, TRUE or FALSE Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns TRUE if the file was successfully closed. FEOF(integer) Returns: INTEGER, TRUE or FALSE Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns TRUE if the current file pointer position is at the end of file. FERROR(integer) Returns: INTEGER, error code Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns FALSE if no error has occurred accessing the indicated file, else it is an error code. FGETC(integer) Returns: INTEGER, character code or -1 Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function returns the next character in a file which has been opened for input. A -1 result is used to indicate end-of-file or error (See FEOF and FERROR). FGETS(integer) Returns: STRING, input from file Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function reads a line of text from a file opened for input. It reads all characters up to and including a newline character ("^J", see notes on file handling for information about newline translation) or 1024 characters, whichever occurs first. It returns and empty string to indicate end-of-file or error (See FEOF and FERROR). FOPEN(string, string) Returns: INTEGER, file handle Notes: This function MAY NOT be called outside the context of and assignment statement. It opens a file and its return value is a "handle" for all the other file oriented functions (FGETC, FEOF, FCLOSE, etc). Care should be taken with this value so that it not altered in any way until FCLOSE has safely been called. The first argument is a file name, the second is the open "mode" and should be one of "r", "w", "a", "rt", "rb", "wt", "wb", "at", "ab", "r+t", "w+t", "a+t", "r+b", "w+b", or "a+b" (see notes on file handling for an explanation). If the function returns 0, the file was not opened. FPUTC(integer, integer) Returns: INTEGER, the output character or -1 Notes: The second argument should be the value returned from an earlier call to FOPEN (see notes on file handling). The first argument is the ascii value of the character to be output to the file, the file must have been opened in a mode which allows writing of data ("w", "a", etc). A return value of -1 indicates an error situation (see FEOF and FERROR). FPUTS(string, integer) Returns: INTEGER, the last output character or -1 Notes: The second argument should be the value returned from an earlier call to FOPEN (see notes on file handling). The first argument is the string to write to the file. The file must have been opened in a mode which allows writing of data ("w", "a", etc). A return value of -1 indicates an error (see FEOF and FERROR). FSEEK(integer, integer, special) Returns: INTEGER, TRUE or FALSE Notes: The first argument should be the value returned from an earlier call to FOPEN (see notes on file handling). The second integer specifies an offset into the file which may be positive, negative, or zero depending upon the mode specified in the third argument. This function will attempt to move the current file location pointer in the indicated file to a number of bytes (specified in the second argument) from the origin (specified in the third argument). The third argument MUST be one of: 0 -- beginning of file 1 -- current position in file 2 -- end of file If this function returns false, an error has occurred. (see FEOF and FERROR) FTELL(integer) Returns: INTEGER, Notes: The argument should be the value returned from an earlier call to FOPEN (see notes on file handling). This function retrieves the current location pointer in the indicated file. A return value of -1 indicates an error (see FOEF and FERROR). GETC(void) Returns: INTEGER, keystroke value or zero Notes: Waits for the user to type a key and returns the value of the keystroke. If an error occurred, the return is zero, if it was a 'standard' key, the return is the ASCII value of the keystroke, if it was an 'extended' key (i.e., Alt key or function key) it returns the scan code of the key times 256. The keystroke is NOT echoed to the terminal screen. (See GETS) GETENV(string) Returns: STRING Notes: This function will scan the OS/2 environment table for the current process (TE/2) and retrieve the value associated with the string specified in its argument or the empty string if the argument was not found in the environment. Examples: CmdExe = GETENV("COMSPEC") MESSAGE("%s", GETENV("PROMPT")) GETYESNO(string, string, integer) Returns: INTEGER, User selection result Notes: Displays the Yes/No dialog (TE/2 uses this dialog for querying the user for hangup and exit). Both strings are centered in the dialog, string2 may be NULL. The integer determines the default answer (TRUE for Yes, FALSE for No). DLogNormAttr and DLogHiAttr from the initialization file are used for the dialog colors. The portion of the screen overlaid by the dialog are saved and restored when the dialog is exited. Returns TRUE if "Yes" was selected, FALSE if "No" was selected. GETS(integer) Returns: STRING Notes: Gets a string from the console at the current cursor location. The argument specifies the maximum length of the string, it may be a number from 1 to 255. If it is less than one, an empty string is immediately returned, if it is greater than 255, it is treated as if it were 255. GETS retrieves a string from the user up to, but not including the first carriage return character or the maximum length whichever occurs first. Backspace will erase the previous character typed (if any) and the ESCape key will immediately terminate the input and GETS will return an empty string. If terminal display is turned on (see TERMECHO) the input is echoed to the terminal screen in the current attribute and at the current cursor location. (See GETC) HANGUP(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" argument must be one of TRUE, FALSE, or IFCARRIER. If FALSE, the hangup sequence will be unconditionally performed, if TRUE the user will be queried for permission, if IFCARRIER, the user will be queried only if the carrier is high (TE/2 is online). The function returns TRUE if the hangup sequence was successfully transmitted and TE/2 is no longer on line. NOTE: The parameter for the HANGUP() statement will override the current setting of the TE/2 QueryHangUp initialization variable. INTERPRET(string) Returns: INTEGER, always TRUE Notes: Invokes the script parser on its argument and executes it as a script command. Anything that can be typed at the "Command:" prompt can be executed via Interpret(). Examples: INTERPRET("hangup(false)") INTERPRET("downloadpath = ""d:\foo""") ITOA(integer, special) Returns: STRING, ASCII representation of the argument Notes: The "special" argument must be in the range 2-36, it specifies the radix for the conversion (number system base. If the radix is 10 and the value of the first argument is negative, a leading '-' sign is the first character of the result. Examples: ITOA(1234, 10) returns "1234" ITOA(8, 2) returns "1000" JDATE(integer, integer) Returns: INTEGER, A packed date (in the same format as the 'date' read-only variable) based on the given Julian day number in the first parameter. Returns 0 on error. Notes: The first parameter is the Julian Day Number to translate, the second is a Boolean switch. If the second parameter is TRUE, the returned date will be relative to the Gregorian Calendar otherwise it will be relative to the Julian Calendar. If the Julian Day Number is invalid or the results would be out of bounds for the requested calendar, the return value will be 0. (See discussion on Julian date conversions elsewhere in this document.) JULIAN(integer, integer) Returns: INTEGER, Julian Day Number or -1 on error. Notes: The first parameter must be a packed date in the same format as the 'date' read-only variable. The second parameter indicates which calendar to use when translating the date: TRUE means that this is a Gregorian date, FALSE implies a Julian date. The return value is the Julian Day Number for the given date. If the date is invalid for the indicated calendar, this function returns -1. (See discussion on Julian date conversions elsewhere in this document.) JULIAN2(integer, integer, integer, integer) Returns: INTEGER, Julian Day Number or -1 on error. Notes: The parameters are, in order: month number (1 to 12), day number (1 to 31), year number, and a Boolean to indicate which calendar to use when translating this date: TRUE means that this is a Gregorian date, FALSE inplies a Julian Date. The return value is the Julian Day Number for the given date. If the date is invalid for the indicated calendar, this function returns -1. (See discussion on Julian date conversions elsewhere in this document.) JWDAY(integer) Returns: INTEGER, weekday index (0 to 6) or -1 on error. Notes: The single parameter is a Julian Day Number, the function will return the weekday index for that Julian Day (0 is Sunday). If the Julian Day number is invalid, the function returns -1. LFAFTERCR(special) Returns: INTEGER, TRUE or FALSE, the new value of LFafterCR Notes: The "special" parameter must be one of TRUE, FALSE, or TOGGLE. If TRUE or FALSE, the value of the LF-After-CR flag is set to that value, if it is TOGGLE the flag becomes TRUE if it was FALSE and vice-versa. LOCALECHO(special) Returns: INTEGER, TRUE or FALSE, the new value of LocalEcho Notes: The "special" parameter must be one of TRUE, FALSE, or TOGGLE. If TRUE or FALSE, the value of the Local-Echo flag is set to that value, if it is TOGGLE the flag becomes TRUE if it was FALSE and vice-versa. LOGCLOSE(void) Returns: INTEGER, TRUE or FALSE Notes: Closes the currently open log file and returns TRUE, if there is no currently open log file no action is performed and the function returns FALSE. LOGFILE(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-L in terminal mode. If a log file is currently open this function will close it and return TRUE, else the user will be prompted for a log file name to open. In this case it returns TRUE if a log file was opened or FALSE if the user typed ESCape at the prompt of if there was an error opening the file. LOGOPEN(string, integer) Returns: INTEGER, TRUE or FALSE Notes: The first argument specifies the log file to open. This must contain the entire path/name of the file, default logpath handling is NOT performed on this string. The second argument should be TRUE if the the log file should overwrite any existing file of the same name, if FALSE, new data will be appended to the file. If the first argument is NULL, the user will be prompted for the file name and overwrite/append mode, the second parameter is ignored. The function returns TRUE is a log file was successfully opened, FALSE if the file was not opened due to error or user intervention. LOGPAUSE(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" argument must be one of TRUE, FALSE, or TOGGLE. If TRUE, the log file will be placed in the paused state, if FALSE it will be made active, if TOGGLE it will alternate states. The function returns TRUE if an action was performed, if there is no currently open log file, it will return FALSE. MAINMENU(special) Returns: INTEGER, TRUE or FALSE Notes: The "special" argument must be one of -1, 0, 1, or 2 with the following meanings: -1 -> Cycle menu state 0 -> Turn OFF Menu or Status bar 1 -> Turn ON Menu 2 -> TURN ON Status bar The function returns TRUE if the menu state was changed. Note that the system-global variable "MenuActive" may be examined to determine the current state of the menu. MESSAGE(string, ... ) Returns: INTEGER, the length of the message string Notes: MESSAGE takes a parameter list identical to the SPRINTF function, refer to SPRINTF for a more complete discussion of the format string and its arguments. This function will build a string according to the rules for SPRINTF and display it on the terminal screen at the current cursor location. MUXWAIT(string, integer) Returns: INTEGER Notes: Very much like the related WAITFOR function, MUXWAIT allows you to specify, in the its first argument, as many as 10 strings to wait for. The first character of the string argument defines the delimiter that will be in effect for parsing the seperate wait strings. This may be any character you choose bit it should be a character that does not otherwise appear in any of the substrings (see the examples). MUXWAIT does not return until one of the specified strings has been encountered at the comm port, the duration in seconds specified in the second argument has elapsed, or the user types ESCape, whichever occurs first. Returns the index of the string which was found or FALSE if a timeout occured or the wait was aborted by typing ESCape. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. (See WAITFOR, WATCHFOR) If the second parameter is less than zero, normal timeout processing is disabled and MUXWAIT will not return until a string has been matched or an ESCape is typed at the keyboard. Examples: MUXWAIT("/ENTER to continue/Select:/", 60) The above example will wait up to 60 seconds for either the string "ENTER to continue" or "Select:" to appear at the comm port. If, for instance, "Select:" was encountered, the function returns 2. MUXWAIT("!Enter name/userid:!What system?!", 30) Note the use of "!" as the delimiter in this example rather than the "/" used in the first. This example needs to use the slash as a valid character in one of its searches thus the different delimiter is mandated. OPENDIALOG(integer, integer, integer, integer, integer) Returns: INTEGER, handle to created dialog Notes: Creates a dialog box on screen complete with frame and shadow. The arguments are, in order, top row, left column, bottom row, right column, and color attribute. The contents of the portion of the screen overlaid by the dialog box are saved and will be restored with a subsequent call to CLOSEDIALOG. The return value is a 'handle' to the dialog. PARMSMNU(void) Returns: INTEGER, always FALSE Notes: This is equivalent to typing Alt-P from terminal mode. The system-global variables "Device", "Port", "Baud", "WordLen", and "StopBits" may be examined to determine the current line settings at any time. PASSWORD(string) Returns: STRING Notes: The parameter is either a "tag" to search for in the currently loaded dialing directory, "#nnn" where "nnn" is an entry's position in the directory, or it may be "" in which case it refers to the most recently dialed entry. Returns the value of the "Password" field in the specified entry or "" if it could not be located. PGMMENU(void) Returns: INTEGER, always TRUE Notes: This is equivalent to typing Alt-J in terminal mode. PLAYFILE(string, integer) Returns: INTEGER, 0 if no error or an error value Notes: The string parameter should be the name of an MMOS2 "playable" file (.WAV, .VOC, etc). The integer parameter should be set to TRUE is you wish the PLAYFILE function to wait until MMOS2 is finished playing the file before returning or FALSE if you wish asychronous play. In asychronous mode, PLAYFILE always returns 0. This function is only valid if MMOS2 is installed on the system. (See RECORDFILE) POPKEYBOARD(void) Returns: INTEGER, TRUE or FALSE Notes: "Pops" a keyboard definition that was previously "pushed" via PUSHKEYBOARD() and makes it the current keyboard. The old current keyboard is discarded. Returns TRUE if successful, FALSE if the stack was empty. (See PUSHKEYBOARD, READKEYFILE, QUERYKEYFILE) PUSHKEYBOARD(void) Returns: INTEGER, TRUE or FALSE Notes: "Pushes", or saves, the current keyboard definition on an internal stack for later retrieval via POPKEYBOARD(). The current keyboard definition is then set to all default keystroke values. Returns TRUE if successful or FALSE if an error occured. (See POPKEYBOARD, READKEYFILE, QUERYKEYFILE) QUERYKEYFILE(void) Returns: STRING Notes: Returns the name of the currently loaded key mapping file (loaded via "KeyMapFile" in TE2.INI or the READKEYFILE() function) or the empty string if the default keyboard is in effect. (See POPKEYBOARD, PUSHKEYBOARD, READKEYFILE) QUEUEDIAL(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-Q in terminal mode or "Q" in the dialing directory in that it activates the Queue Dialer. The function returns TRUE if a connection resulted. RESTART(integer) Returns: INTEGER, TRUE or FALSE Notes: Closes and reopens the current "Device". If the integer parameter is set to TRUE, the user will be prompted for action after the device has been closed and before it is reopened. The user may elect to exit TE/2 at this point. If set to FALSE, ReStart() procedes directly to the reopen phase without prompting the user. This function is not available if TE/2 was started with a "hot" handle. If Restart() fails to reopen the device, usually TE/2 will be exited. If Telnet handshaking is enabled, it will be reinitialized. Returns TRUE on success and FALSE on failure (if it returns from failure at all). READKEYFILE(string) Returns: INTEGER, TRUE or FALSE Notes: The string parameter names a TE/2 Keyboard Definition File presumably created via the TE2Kbd utility. This function reads the keyboard definition in the file into the current TE/2 keyboard definition, overwriting the current definitions. Returns TRUE on success, FALSE on FAILURE. (See POPKEYBOARD, PUSHKEYBOARD, QUERYKEYFILE) READSCR(integer, integer, integer) Returns: STRING Notes: The parameters are screen row, screen column, and number of bytes to read respecitvely. Function returns a string containing the screen contents from the specified co-ordinates. RECORDFILE(string, string) Returns: INTEGER, 0 on success or an error value Notes: The first string parameter is the name of an output file which will be created by MMOS2, the second string parameter will the the title bar text for the recorder window. This function is only available if you have MMOS2 installed on your system and may only be called if TE/2 is running "in a window". Furthermore, you should have a microphone installed with your multimedia hardware to successfully use this function. REDIAL(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-R in terminal mode in that the Redialer is activated. The function returns TRUE is a connection resulted. RENAME(string, string) Returns: INTEGER, TRUE or FALSE Notes: This function will attempt to rename the file specified in the first argument to the new name given in the second argument. The function returns TRUE if it was successful, otherwise an error has occurred. Further note, this function may be used to move a file from one subdirectory to another on the same disk but not across disks. Examples: RENAME("logfile.log", "logfile.bak") RENAME("somefile.dat", "\safe\place\somefile.dat") RESTORESCR(integer) Returns: INTEGER, always TRUE Notes: The argument MUST be a handle to a saved screen that has been created via an earlier call to SAVESCR or disaster is sure to follow. This function will restore a previously saved screen setup, restoring the video mode (if neccessary), cursor position, size, and attribute, and the entire contents of the screen and frees up all memory used by SAVESCR. RGETC(integer, special) Returns: INTEGER, received character or 0 Notes: This function retrieves one byte of incoming data. The integer parameter specifies the timeout value in seconds. If the timeout period elapses or the user types an ESCape at the console before a byte of information is received, RGETC returns 0. The second, special parameter determines how TE/2 will echo the character back to the sender. It may be an integer or a string. If it is an integer and is non-zero then the character will be echoed back to the sender, if it is zero, or if it is an empty or NULL string, no character is echoed. Otherwise, the first character of the string is echoed back to the sender (use this for remote entry of passwords, for instance). Note that by specifying a number less than zero as the timeout parameter, timeout processing is disabled. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. Backspaces are processed and filtered by RGETS before returning, if echoing is enabled, backspaces, carriage returns, and line feeds are echoed as themselves regardless of any translation specified in parameter 2. (See RGETS) RGETS(integer, integer, special) Returns: STRING, the received data Notes: This function retrieves incoming data into a string variable up to the first carriage return or the string length specified in the first argument or until the number of seconds specified in the second argument has elapsed, or until the user types an ESCape character at the console, whichever occurs first. The third, special parameter determines how TE/2 will echo the characters back to the sender. It may be an integer or a string. If it is an integer and is non-zero then the characters will be echoed back to the sender, if it is zero, or if it is an empty or NULL string, no characters are echoed. Otherwise, the first character of the string is echoed back to the sender for each received character. (use this for remote entry of passwords, for instance). Note that by specifying a number less than zero as the timeout parameter, timeout processing is disabled. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. Backspaces are processed and filtered by RGETS before returning, if echoing is enabled, backspaces, carriage returns, and line feeds are echoed as themselves regardless of any translation specified in parameter 3. If the length parameter evaluates to 1, backspaces are NOT filtered or translated. (See RGETC) RSHELL(string, string, integer) Returns: INTEGER Notes: Similar in many ways to the SHELL function but subtly different in several important aspects. The first string specifies a program to be executed, the second its arguments. The program argument MUST be specified, there is no default value. When the program is executed, the standard input, standard output, and standard error system handles are all redirected to the comm port. Thus, any program which takes its input from stdin and writes to stdout and/or stderr, will receive its input now from the comm port and send its output back out the comm port. If the third, integer parameter is non-zero TE/2 will continue to monitor the status of the connection while the child process is running. If a loss of carrier is detected, the child program will be aborted and control will return to your script file. TE/2's screen wil be saved and cleared before executing the RSHELL program and restored upon return. The return value is -1 if there was an error otherwise it is the return code of the program. RSHELL processes incoming backspace characters in the expected fashion. The meaning of the third parameter has been expanded. The parameter may take any of the following values either singly or ORed together: 1 --> watch carrier 2 --> echo incoming characters 4 --> translate cr == cr-lf 8 --> buffer remote input & translate backspaces Any other bits set in the parameter are ignored. While in the RSHELL, the remote user has several special key sequences available that will modify the behavior. Each begins with a Control-Backslash (^\, ascii code 28): ^\e --> toggles echoing of characters ^\x --> toggles cr-crlf translation ^\b --> toggles buffering Anything else following a ^\ is simply passed through unchanged (thus ^\^\ == ^\). Note that the character codes ARE case sensitive, that is, ^\B is not the same thing as ^\b. More special codes may be added in the future. SAVEDIRFILE(string) Returns: INTEGER, 0 on success or an eror code Notes: Saves the current dialing directory to disk using the filename specified in the parameter. If the parameter is "" then the file will be saved using its current name. SAVESCR(void) Returns: INTEGER, handle to saved screen information Notes: Saves the current contents of the entire screen and returns a 'handle' to the saved information. This information includes the current video mode, the cursor position, the cursor size and attribute as well as the actual contents of the screen. If SAVESCR returns zero then there was not sufficient memory to perform the operation. SCROLLBACK(void) Returns: INTEGER, TRUE or FALSE Notes: This is equivalent to typing Alt-W from terminal mode. The function returns TRUE unless the Scroll Back feature is disabled in which case it returns FALSE. SETANSIBS(integer) Returns: INTEGER Notes: The integer parameter should be either TRUE or FALSE, this function sets or clears the "ANSIBackspace" flag. Returns the previous value of the flag. SETCTSRTS(integer) Returns: INTEGER, TRUE or FALSE Notes: Sets the Cts/Rts handling according to the argument: 0 - CTS/RTS both off 1 - CTS on, RTS off 2 - RTS on, CTS off 3 - CTS/RTS both on The function returns TRUE if it was successful. SETCURSOR(integer, integer) Returns: INTEGER, TRUE on success, FALSE on error Notes: Places the cursor at (row, column) on the terminal screen. This is direct placement independent of the current terminal emulation. The origin is (usually) the upper lefthand corner and is (0,0). If the current terminal emulation is VT100 AND the virtual terminal is in relative cursor addressing mode AND a scroll region is set, this function will obey the VT100 emulation's rules for cursor placement relative to scrolling region. If the requested location is invalid, this function will return FALSE. SETCURSORSZ(integer, integer) Returns: INTEGER, TRUE on success, FALSE on failure Notes: Sets the size of the cursor, the parameters are the top and bottom scan lines for the cursor. If successful, system global variables CursorTop and CursorBottom are updated. SETFNKEYFILE(string) Returns: INTEGER, 0 on success, 1 on file not found, 2 on read error Notes: Loads a new function key definition file. If the parameter is "" then the user will be queried for the file name. SETMARK(string, special) Returns: INTEGER Notes: The string parameter is a dialing directory tag, "special" is TRUE, FALSE, or TOGGLE. This function sets the mark for the queue dialer on the specified dialing directory entry. Returns the OLD state of the mark for that entry (TRUE or FALSE) or -1 if "tag" was not found. SETNAME(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry, if it is "#nnn" then it is the "nnn"th directory entry. The "Name" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETPARMS(integer, integer, integer, integer, integer) Returns: INTEGER, TRUE or FALSE Notes: The arguments are Portnumber, baudrate, parity, wordlength, and stopbits respectively. SETPARMS returns TRUE if it was able to set the specified parameter configuration. If it was unsuccessful NONE of the parameters were changed. If the port number changes, the original comm port will be closed and any active connection severed. If any of the parameters are to stay the same either the appropriate system-global variable should be used or, alternately a -1 in that position. Examples: SETPARMS(Port, 2400, 0, 8, 0) sets the current comm port to 2400 baud, no parity, 8 bit word length and 1 stop bit. SETPARMS(-1, 2400, 0, 8, 0) is equivalent to the previous example. SETPARMS(-1, 9600, -1, -1, -1) sets the current comm port to 9600 baud and leaves all other settings alone. SETPARMS(Port, 9600, Parity, WordLen, StopBits) is equivalent to the previous example. Further Notes: The following is a list of the numbers to use for setting parity, word length, and stop bits: Parity: 0 - no parity 1 - odd parity 2 - even parity 3 - mark parity 4 - space parity Word Length: 7 - 7 bit words 8 - 8 bit words Stop Bits: 0 - 1 stop bit 1 - 1.5 stop bits 2 - 2 stop bits SETPARMS2(string, integer, integer, integer, integer) Returns: INTEGER, TRUE or FALSE Notes: Exactly like SETPARMS() in all respects except that it takes a string argument for the device name instead of an integer 'port number' so it can be used to switch devices with the device name isn't COMx. (See the SETPARMS for further information) SETPASSWORD(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry, if it is "#nnn" then it will mean the "nnn"th entry. The "Password" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETPHONE(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry, if it is "#nnn" then it will mean the "nnn"th entry. The "Number" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETSCRIPT(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry, if it is "#nnn" then it will mean the "nnn"th entry. The "Script" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETTAG(string, string) Returns: INTEGET, TRUE or FALSE Notes: The first paramter is a "tag" to search the currently loaded dialing directory for; if it is "" then it is taken to mean the most recently dialed entry, if it is "#nnn" then it will mean the "nnn"th entry. The "Tag" field in that entry will be set to the value of the second parameter. Return TRUE on success or FALSE on error. SETXONXOFF(integer) Returns: INTEGER, TRUE or FALSE Notes: If the argument is zero, XonXoff processing will be turned off, if the argument is "1" transmit XonXoff processing will be enabled, if it is "2" receive XonXoff processing will be enabled, if it is "3" both transmit and receive XonXoff processing are enabled. The system-global variable "XonXoff" may be examined at any time to determine the current state of XonXoff processing. The function returns TRUE if it was successful. SETVT100BKSP(integer) Returns: INTEGER Notes: Sets the VT100 emulation backspace translation mode. If the parameter is TRUE then the VT100 eumlation will treat incoming Backspace characters (ASCII 8) as destructive backspaces, if FALSE the VT100 backspace will be non-destructive. Returns the previous setting for the VT100 Backspace handling. SETXLATTABLE(string, integer) Returns: INTEGER Notes: Reads a new character translation table from the file specified in the first parameter. If the second parameter is zero, the new table will replace the input character translation table, if it is non-zero, it will replace the output character translation table. Returns 0 on success or an error code on failure. SENDBREAK(integer) Returns: INTEGER, the value of its argument Notes: Will transmit a break signal to the port for the specified duration in milliseconds. If a zero value is specified, the current value of the system-global variable "BreakLen" is used for the duration. SENDBYTE(integer OR string) Returns: INTEGER, TRUE or FALSE Notes: Sends the byte specified by either the integer expression or the first character of the string expression to the port. If the character is either Ctrl-S or Ctrl-Q, the byte is transmitted immediately. The function returns TRUE if it was successful. SENDINIT(void) Returns: INTEGER, TRUE or FALSE Notes: Transmits the string in the system-global variable "modemInitStrg" to the comm port. Returns TRUE if it was successful. SHELL(string, string) Returns: INTEGER Notes: Executes the program specified in the first argument sending it the parameters specified in the second. If the first argument is NULL, the current value of the system-global variable "ShellCmd" is used unless it is also NULL in which case CMD.EXE is executed with no parameters. If the first argument is NULL, the second argument is ignored. The program is executed synchronously in the foreground, TE/2 is suspended while in the shell. TE/2's screen is saved before and restored after execution. The return value of the function is the return code of the executed program or -1 if an error occurred. SHELL(NULL, NULL) is equivalent to typing Alt-O from terminal mode. SLEEP(integer) Returns: INTEGER, the value of its argument Notes: Suspends execution of TE/2 for the duration in milliseconds specified in its argument. SNAPSHOT(string) Returns: INTEGER Notes: Performs the TE/2 SnapShot function saving its results to the filename indicated in the parameter. If the parameter is "" the the screen capture is saved to the default file name. Snapshot always appends data to the output file. Returns zero on success or an error code on failure. SPRINTF(string, ... ) Returns: STRING Notes: SPRINTF receives a format string in its first argument followed by up to 10 additional arguments that may be either integers or strings. The arguments are formatted into a string according to rules specified by embedded commands in the format string. With the exception of floating point handling and pointer notation, all of the functionality of the "C" functions "printf" and "sprintf" are supported by TE/2's implementation of SPRINTF, the reader is referred to the C Language library reference manual of his or her choice for complete definition of all of the rules regarding format strings. Here we will note the following: All characters from the format string are copied to the output string with the following exceptions: If "%s" is encountered in the format string, the next unexamined parameter is interpreted as a string an embedded at that point in the output string. The notation "%10s" will right justify the string in a field of 10 spaces at that point in the output string. "10" is used by way of example, it may be any decimal number. The notation "%-10s" will likewise left justify the string in a field of 10 spaces. If "%d" is encountered in the format string, the next unexamined parameter is interpreted as a 16 bit signed integer and the ascii representation of it is embedded into the output string at that point. "%ld" interprets the numeric parameter as a 32-bit signed integer (the native form of all integers in the TE/2 script language). "%10d" or "%10ld" right justifies the number in a field of 10 spaces in the output string, "%010d" or "%010ld" right justify the number in a field of ten zeros in the output string. If "%*s", "%-*s", "%*d", et cetera are encountered in the format string, these will behave exactly the same as the examples above with numeric values except that TWO parameters are expected in the argument list, the first an integer which will specify the field width, the second the string or integer to place in the output string. If "%%" is encountered in the format string, a single "%" is placed in the output string. The arguments to SPRINTF may be literal strings, string variables, string expressions, numeric literals, constants, variables, or expressions in any form or order. The only restriction is that the first argument, the format string, must evaluate to a string. WARNING It is not possible to type check all of the parameters in an SPRINTF (or MESSAGE or TRANSMIT) argument list. The script file writer is expected to take precautions to avoid type mismatches so that integers are not interpreted as strings and vice versa. In general, if a string is interpreted as an integer there should be no ill effects other than erroneous output. If an integer is interpreted as a string however, a protection violation may well occur. Examples: SPRINTF("Hello %s", "World") returns "Hello World" SPRINTF("Hello %8s", "world") returns "Hello world" SPRINTF("Hello %-8s", "World") returns "Hello World " SPRINTF("This is the %dth example", 4) returns "This is the 4th example" SPRINTF("Action is %03d%% %s", 35, "complete") returns "Action is 035% complete" STATUS(void) Returns: INTEGER, always FALSE Notes: This is equivalent to typing Alt-I from terminal mode. STREVAL(string) Returns: STRING, the value of its argument Notes: This function is included as a convenience for the REXX language script writer, it simply returns the value of its argument allowing a REXX script to query any TE/2 internal or global variable. STRCMP(string, string) Returns: INTEGER Notes: Lexigraphically compares two strings, returns zero if the strings are identical, less than zero if the first string is "less than" the second, greater than zero otherwise. STRGET(string, integer, integer, integer, integer, integer, integer) Returns: STRING, user response Notes: String input routine. The string parameter is the default value, and the integer parameters are, in order, row for the input, column for the input, width of the input area, maximum input length (may be larger, smaller or equal to the previous parameter), attribute for 'first display' of the default, and attribute for display while the user is editing/inputting. Returns the edited string, returns the empty string if the user pressed ESCape. Note that input area is NOT saved and restored, it will remain on screen after the input. STRICMP(string, string) Returns: INTEGER Notes: Case-insensitive version of STRCMP. See STRCMP. STRLEFT(string, integer) Returns: STRING Notes: Returns the leftmost N characters in the string where N is the number specified in the second argument. If N is greater than the length of the string, the entire string is returned. (see STRRIGHT, SUBSTR) STRLEN(string) Returns: INTEGER, the length of the string STRNSTR(string, string, integer) Returns: INTEGER Notes: The integer parameter specifies a match count (n), this function finds the n-th occurance of the second string in the first. STRNSTR(s1, s2, 1) is identical to STRSTR(s1, s2). STRPUT(integer, integer, integer, string, ... ) Returns: INTEGER, length of displayed string Notes: The integer parameters are, in order, screen row, screen column, and attribute for display. The string is a format string (see SPRINTF) which may be followed by up to ten additional arguments. The resulting string is placed at the indicated position on screen using the indicated attribute. Return value is the length of the displayed string. STRRIGHT(string, integer) Returns: STRING Notes: Returns the rightmost N characters in the string where N is the number specified in the second argument. If N is greater than the length of the string, the entire string is returned. (see STRLEFT, SUBSTR) STRSTR(string, string) Returns: INTEGER Notes: Scans the string in the first argument for an occurrence of the string in the second. Returns zero if the string was not found else it returns the position of the second string in the first. STRTRIM(string) Returns: STRING Notes: Returns a string which is a copy of the string in its argument with all leading space, tab, carriage return, and newline characters removed from the beginning and end. Embedded spaces, etc., are not removed. SUBSTR(string, integer, integer) Returns: STRING Notes: Returns a substring of the string in its argument. If N is the value of the second argument and M the value of the third, SUBSTR returns the string which begins N characters into the first argument and continues for M characters. If N is greater than the length of the string, the empty string is returned, if N+M is greater than the length of the string, only the characters in the string from position N to the end of the string are returned. (see STRLEFT and STRRIGHT) TERMECHO(special) Returns: INTEGER, TRUE or FALSE Notes: The special argument must be one of TRUE, FALSE, or TOGGLE. TERMECHO will enable or disable the echoing of characters to the terminal screen. This effects both incoming characters from the comm port received during a WAITFOR, MUXWAIT, RGETS, or RGETC and characters typed at the keyboard during a GETS call. It does NOT have any effect on characters received during a main or higher level PROCESS. Example: message("Enter string to wait for:") termecho(FALSE) waitSrch = gets(255) ; no screen echo here waitfor(waitSrch, 60) ; or here process ; screen will update during this ; but will still be off when we ; get back TERMWINDOW(integer, integer, integer, integer) Returns: INTEGER, TRUE on success, FALSE on error Notes: The parameters specify, in order: row, columns, number of rows, and number of columns for the new emulation window. This function resets the terminal window (a subset of the physical screen) to the size and location specified. It's recommended that you perform a CLS() before and after this call. Take great care with this one, it's a direct back door into the terminal emulation handler. TOLOWER(string) Returns: STRING Notes: Returns a string which is a copy of its argument with all upper case letters translated to lower case. (see TOUPPER) TOUPPER(string) Returns: STRING Notes: Returns a string which is a copy of its argument with all lower case letters translated to upper case. (see TOLOWER) TRACE(integer) Returns: INTEGER, the value of its argument Notes: Enables and disables trace mode during script file execution. When in trace mode each line of the script file is printed on the terminal display (and will appear in the scroll back buffer and log file if one is open) as it is encountered. This is a global toggle, once turned on it is on for all subsequent script file processing until it is turned off again or until TE/2 ends. TRANSMIT(string, ... ) Returns: INTEGER, the length of the message string Notes: TRANSMIT takes a parameter list identical to the SPRINTF function, refer to SPRINTF for a more complete discussion of the format string and its arguments. This function will build a string according to the rules for SPRINTF and transmit it to the comm port. UNIQUEFNAME(string) Returns: STRING Notes: Creates a temporary file name based on 'template' which is a basename plus wildcard characters '?'. For example: C:\TEMP\FILE????. The function does NOT open the file. Returns the empty string if no new names could be generated. UPLOAD(special, string) Returns: INTEGER, TRUE or FALSE Notes: The "special" parameter must be one of the following pre-defined constants: ASCII, XMODEM, XMODEM1K, YMODEM, YMODEMG, ZMODEM, or QUERY. If this parameter is QUERY, the user is prompted for the protocol. The second parameter is the file name, if it is the empty string, the user is prompted for the file name. The function returns TRUE if the file transfer ended with no fatal errors. (See DOWNLOAD) WAITFOR(string, integer) Returns: INTEGER, TRUE or FALSE Notes: Does not return until either the string specified in the first parameter is encountered at the comm port, the duration in seconds specified in the second parameter has elapsed, or the user types ESCape, whichever occurs first. Returns TRUE if the string was encountered, FALSE if a timeout occurred or the wait was aborted by typing ESCape. Note that specifying a number less than zero as the timeout parameter, timeout processing is disabled. Incoming characters are echoed to the terminal screen unless terminal display is turned off, the log file is maintained. (See MUXWAIT, WATCHFOR) WATCHFOR(string, string) Returns: INTEGER, 'handle' for installed watch Notes: Unlike WAITFOR, which does not return until the indicated string has been encountered or a set period of time has elapsed, WATCHFOR installs an asynchronous 'watch' and returns immediately. The return value is zero if TE/2 could not install this watch, only 10 watches may be active at any time. If successful, the return value is a 'handle' which you will need to pass to CANCELWATCH when you want to end the watch. This handle is therefore every bit as precious as the handle returned from FOPEN and the warnings given below in the notes about file handles apply equally well to watch handles. The first parameter is the string to 'watch' for. The second parameter may be nearly any valid TE/2 Script Language assignment statement or function call. The statement is not checked for proper syntax or variable usage until the watch string has been matched and TE/2 attempts to execute the statement so you must take care that the syntax is correct and that any variables referred to in the statement will be accessible when the statement is to be executed. Global and system-global variables are always safe but local variables will cause problems if the watch is left to continue after the current script has finished execution or during the execution of any nested script files or recursive PROCESSes. Every incoming character from the com port is checked against the currently active watches, if a watch string is matched it is tagged for execution. If TE/2 is in a process loop at the time, it will be immediately executed. However, if a script file is running at the time, it will not execute until the current line has finished execution - this means that a WAITFOR, MUXWAIT, RGETS, RGETC, etc., will not be interrupted to execute a watch command. Use the function CANCELWATCH to release a watch that is no longer needed. (See CANCELWATCH) Example: integer whand1 integer whand2 integer gotMail = FALSE program whand1 = watchfor("ENTER to continue", "sendbyte(13)") whand2 = watchfor("mail waiting", "gotMail = TRUE") waitfor("Enter your choice:", 120) cancelwatch(whand1) cancelwatch(whand2) if gotMail ; et cetera WINDOWMINMAX(integer) Returns: INTEGER, 0 on success or an error value Notes: Sets TE/2's window state. The integer parameter should be one of: 0 -> Minimize 1 -> Maximize 2 -> Restore This function not available if TE/2 is running in full screen mode